home *** CD-ROM | disk | FTP | other *** search
/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / mint / mintmant / fcntl.txt < prev    next >
Text File  |  1992-03-24  |  14KB  |  394 lines
  1. Fcntl(2)                  Feb. 18, 1992                  Fcntl(2)
  2.  
  3.  
  4.  
  5. NAME
  6.      Fcntl - perform various control operations on a file
  7.  
  8. SYNOPSIS
  9.      #include <filesys.h>
  10.  
  11.      LONG Fcntl( WORD fh, LONG arg, WORD cmd);
  12.  
  13. DESCRIPTION
  14.      Fcntl performs various control operations on the  open  file
  15.      with GEMDOS file handle fh.  The specific command to perform
  16.      is given by cmd; the possible commands are given by symbolic
  17.      constants  in  filesys.h,  and  are listed below.  arg is an
  18.      argument whose meaning depends on the command.
  19.  
  20.      The following commands are applicable to any  file  descrip-
  21.      tor:
  22.  
  23.      F_DUPFD
  24.           Return a duplicate for the file handle. The new (dupli-
  25.           cate)  handle will be an integer >= arg and < 32. If no
  26.           free handles  exist  in  that  range,  ENHNDL  will  be
  27.           returned.  The  Fdup(fh)  system  call is equivalent to
  28.           Fcntl(fh, 6L, F_DUPFD)
  29.  
  30.      F_GETFD
  31.           Return the noinherit flag for the file descriptor. This
  32.           flag  is  1  if child processes started by Pexec should
  33.           inherit this open file, and 0 if not.  arg is ignored.
  34.  
  35.      F_SETFD
  36.           Set the noinherit flag for the file descriptor from the
  37.           low order bit of arg.  The default value of the flag is
  38.           1 for handles 0-5 (the "standard" handles)  and  0  for
  39.           other  (non-standard)  handles. Note that the noinherit
  40.           flag applies only to this particular  file  descriptor;
  41.           another  descriptor obtained from fh by the Fdup system
  42.           call or by use of the F_DUPFD option to Fcntl will have
  43.           the  noinherit  flag set to the default. Also note that
  44.           these defaults are not the same as for the Unix operat-
  45.           ing system.
  46.  
  47.      F_GETFL
  48.           Returns the user-settable file descriptor flags.  These
  49.           flags  are the same as the mode passed to Fopen, unless
  50.           they have been further modified by another Fcntl opera-
  51.           tion.  arg is ignored.
  52.  
  53.      F_SETFL
  54.           Set user-settable file descriptor flags from the  argu-
  55.           ment  arg.  Only the user-settable bits in arg are con-
  56.           sidered; the settings of other bits  are  ignored,  but
  57.  
  58.  
  59.  
  60. Version 0.93  Last change: MiNT Programmer's Manual             1
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67. Fcntl(2)                  Feb. 18, 1992                  Fcntl(2)
  68.  
  69.  
  70.  
  71.           should  be  0 for future compatibility. Moreover, it is
  72.           not possible to change  a  file's  read-write  mode  or
  73.           sharing  modes  with  this call; attempts to do so will
  74.           (silently) fail.
  75.  
  76.      F_GETLK
  77.           arg is a pointer to an flock structure:
  78.           struct flock {
  79.                short l_type;  /* type of lock */
  80.           #define F_RDLCK          0
  81.           #define F_WRLCK          1
  82.           #define F_UNLCK          3
  83.                short l_whence;     /* 0:file start, 1:current, 2:EOF */
  84.                long l_start;  /* offset of locked region */
  85.                long l_len;    /* 0 for rest of file */
  86.                short l_pid;   /* set by F_GETLK */
  87.           };
  88.           If a lock exists which would  prevent  this  lock  from
  89.           being  applied to the file, the existing lock is copied
  90.           into the structure and the l_pid field is  set  to  the
  91.           process id of the locking process. Otherwise, l_type is
  92.           set to F_UNLCK.
  93.  
  94.      F_SETLK
  95.           Set (if l_type is F_RDLCK  or  F_WRLCK)  or  clear  (if
  96.           l_type  is  F_RDLCK) an advisory lock on a file. If the
  97.           file is a FIFO,  the  whole  file  must  be  locked  or
  98.           unlocked  at  once,  i.e.  l_whence, l_start, and l_len
  99.           must be 0. If this lock would conflict with a lock held
  100.           by  another process, ELOCKED is returned. If an attempt
  101.           is made  to  clear  a  non-existent  lock,  ENSLOCK  is
  102.           returned.   FSTAT  arg  points  to  an XATTR structure,
  103.           which is filled in with the appropriate  extended  file
  104.           attributes  for  the  file  to  which fd refers just as
  105.           though the Fxattr system call (q.v.) had been  made  on
  106.           the file.
  107.  
  108.      FIONREAD
  109.           arg points to a 32 bit integer, into which  is  written
  110.           the  number of bytes that are currently available to be
  111.           read from this descriptor; a read  of  this  number  of
  112.           bytes  or  less  should  not cause the process to block
  113.           (wait for more input).  Note that for some  files  only
  114.           an  estimate  can  be  provided,  so  the number is not
  115.           always completely accurate.
  116.  
  117.      FIONWRITE
  118.           arg points to a 32 bit integer, into which  is  written
  119.           the  number  of  bytes that may be written to the indi-
  120.           cated file descriptor without causing  the  process  to
  121.           block.   Note  that for some files only an estimate can
  122.           be provided, so the number  is  not  always  completely
  123.  
  124.  
  125.  
  126. Version 0.93  Last change: MiNT Programmer's Manual             2
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133. Fcntl(2)                  Feb. 18, 1992                  Fcntl(2)
  134.  
  135.  
  136.  
  137.           accurate.
  138.  
  139.      The following commands are valid for  any  terminal  device,
  140.      e.g. the console or a pseudo-terminal:
  141.  
  142.      TIOCGETP
  143.           Get terminal parameters.  arg is a pointer to  a  block
  144.           of memory with the following structure:
  145.           struct sgttyb {
  146.                char sg_ispeed;          /* reserved */
  147.                char sg_ospeed;          /* reserved */
  148.                char sg_erase;      /* erase character */
  149.                char sg_kill;       /* line kill character */
  150.                short sg_flags;          /* terminal control flags */
  151.           };
  152.  
  153.      TIOCSETP
  154.           Set terminal parameters from the struct sgttyb  pointed
  155.           to by arg.
  156.  
  157.      TIOCGETC
  158.           Get terminal control characters.  arg is a  pointer  to
  159.           the following structure:
  160.           struct tchars {
  161.                char t_intrc;  /* raises SIGINT */
  162.                char t_quitc;  /* raises SIGQUIT */
  163.                char t_startc; /* starts terminal output */
  164.                char t_stopc;  /* stops terminal output */
  165.                char t_eofc;   /* marks end of file */
  166.                char t_brkc;   /* marks end of line */
  167.           };
  168.  
  169.      TIOCSETC
  170.           Set terminal control characters from the struct  tchars
  171.           pointed  to by arg.  Setting any character to the value
  172.           0 causes the corresponding function to become  unavail-
  173.           able.
  174.  
  175.      TIOCGLTC
  176.           Get extended terminal control characters, and put  them
  177.           in the structure pointed to by arg:
  178.           struct ltchars {
  179.                char t_suspc;  /* raises SIGTSTP now */
  180.                char t_dsuspc; /* raises SIGTSTP when read */
  181.                char t_rprntc; /* redraws the input line */
  182.                char t_flushc; /* flushes output */
  183.                char t_werasc; /* erases a word */
  184.                char t_lnextc; /* quotes a character */
  185.           };
  186.  
  187.      TIOCSLTC
  188.           Set  extended  terminal  control  characters  from  the
  189.  
  190.  
  191.  
  192. Version 0.93  Last change: MiNT Programmer's Manual             3
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199. Fcntl(2)                  Feb. 18, 1992                  Fcntl(2)
  200.  
  201.  
  202.  
  203.           struct  ltchars  pointed to by arg.  Setting any of the
  204.           characters to 0 causes the  corresponding  function  to
  205.           become unavailable.
  206.  
  207.      TIOCGWINSZ
  208.           arg has type "struct winsize  *".  The  current  window
  209.           size for this window is placed in the structure pointed
  210.           to by arg, which has the following fields:
  211.           struct winsize {
  212.                short     ws_row;   /* # of rows of text in window*/
  213.                short     ws_col;   /* # of columns of text */
  214.                short     ws_xpixel; /* width of window in pixels */
  215.                short     ws_ypixel; /* height of window in pixels */
  216.           };
  217.           If any fields in the structure are 0, this  means  that
  218.           the corresponding value is unknown.
  219.  
  220.      TIOCSWINSZ
  221.           arg has type "struct winsize  *".  The  current  window
  222.           size  for  the window is set from the structure pointed
  223.           to by arg.  Note that the kernel maintains the informa-
  224.           tion  but  does not act upon it in any way; it is up to
  225.           window managers to perform  whatever  physical  changes
  226.           are  necessary  to  alter the window size, and to raise
  227.           the SIGWINCH signal if necessary.
  228.  
  229.      TIOCGPGRP
  230.           arg has type "long *"; the process group for the termi-
  231.           nal is placed into the long pointed to by it.
  232.  
  233.      TIOCSPGRP
  234.           arg has type "long *"; the process group for the termi-
  235.           nal is set from the long pointed to by it. Processes in
  236.           any other process group will be sent job  control  sig-
  237.           nals if they attempt input or output to the terminal.
  238.  
  239.      TIOCSTART
  240.           Restart output to the  terminal  (as  though  the  user
  241.           typed  control-Q)  if  it was stopped by a control-S or
  242.           TIOCSTOP command.  arg is ignored.
  243.  
  244.      TIOCSTOP
  245.           Stop output to the terminal (as though the  user  typed
  246.           control-S).  arg is ignored.
  247.  
  248.      TIOCGXKEY
  249.           Get the definition of a function or cursor key.  arg is
  250.           a pointer to a structure with the following fields:
  251.           struct xkey {
  252.                short     xk_num;      /* function key number */
  253.                char xk_def[8]; /* associated string */
  254.           };
  255.  
  256.  
  257.  
  258. Version 0.93  Last change: MiNT Programmer's Manual             4
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265. Fcntl(2)                  Feb. 18, 1992                  Fcntl(2)
  266.  
  267.  
  268.  
  269.           The xk_num field must be initialized with the number of
  270.           the desired key:
  271.             xk_num   Key
  272.              0-9         F1-F10
  273.             10-19        F11-F20 (shift F1-shift F10)
  274.              20          cursor up
  275.              21          cursor down
  276.              22          cursor right
  277.              23          cursor left
  278.              24          help
  279.              25          undo
  280.              26          insert
  281.              27          clr/home
  282.              28          shift+cursor up
  283.              29          shift+cursor down
  284.              30          shift+cursor right
  285.              31          shift+cursor left
  286.           The string currently associated with the indicated  key
  287.           is  copied  into  xk_def;  this  string is always null-
  288.           terminated.
  289.  
  290.      TIOCSXKEY
  291.           arg is a structure of  type  struct  xkey,  as  defined
  292.           above.  Both  the  xk_num and the xk_def fields must be
  293.           defined. After execution of this command,  and  if  the
  294.           XKEY  bit  is  set  in the sg_flags field of the sgttyb
  295.           structure associated with the  terminal,  then  if  the
  296.           indicated  key is pressed on the affected terminal, any
  297.           MiNT domain process using Fread to read  the  key  will
  298.           get  the string in xk_def instead of ASCII 0. Note that
  299.           this translation occurs only for MiNT domain  processes
  300.           and  only for the Fread system call. Also note that the
  301.           string in xk_def must be null  terminated,  and  so  at
  302.           most 7 characters may be assigned to any key.
  303.  
  304.      The following commands are valid only for  processes  opened
  305.      as files:
  306.  
  307.      PBASEADDR
  308.           arg is a pointer to a 32 bit integer,  into  which  the
  309.           address  of  the  process  basepage  for the process to
  310.           which fh refers is written.
  311.  
  312.      PPROCADDR
  313.           arg is a pointer to a 32 bit integer,  into  which  the
  314.           address  of  the process control structure for the pro-
  315.           cess is  written.  Note  that  this  control  structure
  316.           differs from the one found in previous versions (before
  317.           0.93) of MiNT; it no longer includes the  process  con-
  318.           text, so that this part of the structure may be changed
  319.           without  causing  compatibility   problems.   See   the
  320.           PCTXTSIZE command.
  321.  
  322.  
  323.  
  324. Version 0.93  Last change: MiNT Programmer's Manual             5
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331. Fcntl(2)                  Feb. 18, 1992                  Fcntl(2)
  332.  
  333.  
  334.  
  335.      PCTXTSIZE
  336.           arg is a pointer to a 32 bit integer,  into  which  the
  337.           length of a process context structure is written. There
  338.           are two of these  structures  located  in  memory  just
  339.           before  the  process control structure whose address is
  340.           returned by the PPROCADDR command.  The  first  is  the
  341.           current  process  context; the second is the saved con-
  342.           text from the last system call.
  343.  
  344. RETURNS
  345.      0 or a positive number if successful (for most commands,  0,
  346.      but see the specific descriptions above).
  347.  
  348.      EIHNDL if fh is not a valid GEMDOS open handle.
  349.  
  350.      EINVFN if the specified command is not valid for  this  file
  351.      handle
  352.  
  353.      Some other (LONG) negative error number if an error  occurs;
  354.      different commands may recognize different possible errors.
  355.  
  356. SEE ALSO
  357.      Fdup(2),   Flock(2),   Fopen(2),   Fxattr(2),   Pgetpgrp(2),
  358.      Psetpgrp(2)
  359.  
  360. BUGS
  361.      Very little error checking is done. In particular, ownership
  362.      of  terminals  is  not  properly  checked, nor is read/write
  363.      access to the files. Do not rely on this  bug;  it  will  be
  364.      fixed some day.
  365.  
  366.      File locking is not yet implemented for most file systems.
  367.  
  368.      Very few of the terminal control options have effect on ter-
  369.      minals connected via serial ports or midi. In particular, it
  370.      is not possible to set the baud rate, parity, flow  control,
  371.      or  similar  options  with Fcntl.  However, this bug will be
  372.      fixed in future versions of the operating  system,  so  pro-
  373.      grams  should  never  modify  the  sg_ispeed,  sg_ospeed, or
  374.      sg_flags fields of the sgttyb structure, and  should  always
  375.      use TIOCGETP to obtain the original settings of these fields
  376.      before calling TIOCSETP.
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390. Version 0.93  Last change: MiNT Programmer's Manual             6
  391.  
  392.  
  393.  
  394.